AllocContig

AllocContig
Header:	Files.h		Carbon status:	Supported

Allocates additional contiguous blocks to an open file.

OSErr AllocContig (
    SInt16 refNum, 
    SInt32 *count
);

refNum: The file reference number of an open file.
count: On input, a pointer to the number of additional bytes to allocate to the file; on output, a pointer to the number of bytes allocated, rounded up to the nearest multiple of the allocation block size.

function result: A result code.

DISCUSSION

The AllocContig function is identical to the Allocate function except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, AllocContig does nothing and returns dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled by the allocation of a contiguous piece, call Allocate instead.

The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the Allocate or AllocContig function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

When the File Manager allocates (or deallocates) file blocks automatically, it always adds (or removes) blocks in clumps. The AllocContig function allows you to add blocks in allocation blocks, which may be smaller than clumps.

The AllocContig function is not supported by AppleShare volumes. Instead, use SetEOF or PBSetEOF to extend a file by setting the end-of-file.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.